home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / PCX_LIB.ARJ / PCX_FMT.DOC < prev    next >
Text File  |  1991-08-11  |  29KB  |  942 lines
  1.  
  2.  
  3. Ian Ashdown
  4. byHeart Software
  5. 620 Ballantree Road
  6. West Vancouver, B.C.
  7. Canada V7S 1W3
  8.  
  9. Issue 1: 91/02/12
  10. Issue 2: 91/03/27
  11. Issue 3: 91/08/08
  12. Issue 4: 91/08/11
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                                PCX Graphics
  25.  
  26.                                     by 
  27.  
  28.                                Ian Ashdown
  29.                              byHeart Software
  30.  
  31. Looking to add monochrome or full-color bit-mapped graphics to your 
  32. application programs?  If so, you might consider the PCX graphics file 
  33. format.  Originally developed in 1982 by ZSoft Corporation for their PC 
  34. Paintbrush (R) products, it has become a de facto industry standard for 
  35. storing and transferring bit-mapped images on MS-DOS machines.  It can 
  36. support displays of any resolution using palettes of up to 256 
  37. simultaneous colors, and is very simple to implement.  Furthermore, it's 
  38. not limited to MS-DOS and OS/2-based machines; the PCX format is 
  39. applicable to any environment supporting bit-mapped graphics. 
  40.  
  41. Today, more commercial programs support ZSoft's PCX format than any 
  42. other, including Aldus-Microsoft's Tag Image File Format (TIFF).  
  43. However, unlike TIFF with its publicly-available technical 
  44. specifications, the PCX file format has never been completely documented.  
  45. When ZSoft first created PC Paintbrush, the only video displays they had 
  46. to contend with were two monochrome adapters (Hercules and Tecmar) and 
  47. the IBM Color Graphics Adapter (CGA).  They have since quietly modified 
  48. and extended their format on several occasions to support EGA, VGA and 
  49. SuperVGA displays.  Documentation is scarce, incomplete and sometimes 
  50. contradictory.  There's a small booklet available from ZSoft that 
  51. describes the current version (with several omissions), a sample Pascal 
  52. program from their CompuServe forum (GO WINAPB), a few magazine articles, 
  53. and chapters in a few books (see the references at the end of this 
  54. article). 
  55.  
  56. Personally, I think it's about time to remedy this situation.  The 
  57. following is a complete set of technical specifications for the current 
  58. version of PCX.  All of the information has been derived from printed 
  59. information provided by ZSoft and conversations with their Technical 
  60. Services department.  This is it, folks!  We now have formal (if not 
  61. exactly official) specifications to work with when including the PCX 
  62. graphics file format in our application programs. 
  63.  
  64. My original plan was to include sample C source code for reading and 
  65. writing PCX image files.  However, both this article and the source code 
  66. grew to the extent that one had to go.  If you don't want to develop your 
  67. own PCX file handling routines from scratch, PCX_LIB is available through 
  68. the CUG Library as CUG Volume #???.  It includes fully commented C source 
  69. code for reading and writing PCX image files, complete with software 
  70. drivers for Hercules, CGA, EGA, and VGA display adapters.
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.                                                                     p. 1
  91.  
  92. PCX Specifications 
  93.  
  94. The PCX graphics file format (Version 5) is designed to store monochrome 
  95. and color bit-mapped images of any resolution with palettes of up to 256 
  96. simultaneous colors.  It was originally designed for MS-DOS 
  97. microcomputers, but is adaptable to other bit-mapped graphic 
  98. environments.  A simple but effective byte-oriented, run-length encoding 
  99. scheme is used to compress the image data.
  100.  
  101. There are two or three sections to a PCX graphics file - a 128-byte 
  102. header, the encoded image data (which can be of any length) and an 
  103. optional 256-color palette (see Figure 1).  This palette is appended to 
  104. the file only if the image contains more than 16 colors. 
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.                                                                     p. 2
  152.  
  153. 1.  PCX File Header
  154.  
  155. The file header describes the graphical environment in which the image is 
  156. to be displayed.  The information contained in the header is somewhat 
  157. device-dependent in that the PCX file format implicitly assumes the 
  158. presence of a standard IBM PC-compatible display adapter.  Furthermore, 
  159. the specific type and video mode of the adapter needed to display the 
  160. image correctly cannot be uniquely determined from the file header 
  161. information.  It is in general the user's responsibility to ensure that 
  162. the correct video mode has been selected before displaying a PCX image. 
  163.  
  164. The file header structure is shown in Figure 2.  A complete description 
  165. of each structure member is as follows: 
  166.  
  167. 1.1   PCX Flag
  168.  
  169. A constant value (0x0a) that signifies a PCX image file. 
  170.  
  171. 1.2   Version
  172.  
  173. Indicates the PCX file format version. It can be one of five values: 
  174.  
  175.     0 - Version 2.5 of PC Paintbrush.
  176.     2 - Version 2.8 (with palette information).
  177.     3 - Version 2.8 (without palette information).
  178.     4 - PC Paintbrush for Windows (not 3.0).
  179.     5 - Version 3.0 and greater of PC Paintbrush and Paintbrush Plus, 
  180.         including Publisher's Paintbrush. 
  181.  
  182. Most commercial programs supporting the PCX file format conform to 
  183. Version 5.  See Section 3, "Color Palettes", for further information. 
  184.  
  185. 1.3   Encoding (1)
  186.  
  187. A constant value (0x01) that indicates run-length encoding was used to 
  188. encode and compress the image data. 
  189.  
  190. 1.4   Bits per Pixel
  191.  
  192. The number of bits per pixel per color plane (typically 1, 2, 4 or 8). 
  193.  
  194. 1.5   Window
  195.  
  196. A structure with the following members: 
  197.  
  198.     Name    Bytes    Description
  199.  
  200.     xul       2      Upper left corner horizontal position
  201.     yul       2      Upper left corner vertical position
  202.     xlr       2      Lower right corner horizontal position
  203.     ylr       2      Lower right corner vertical position
  204.  
  205. These members describe the position and size of the image within the 
  206. display, and are measured in pixels (starting with zero). 
  207.  
  208.  
  209.  
  210.  
  211.  
  212.                                                                     p. 3
  213.  
  214. 1.6   HDPI (2)
  215.  
  216. "Horizontal dots per inch".  The value represents the horizontal 
  217. resolution of the device used to create the image. 
  218.  
  219. 1.7   VDPI (2)
  220.  
  221. "Vertical dots per inch".  The value represents the vertical resolution 
  222. of the device used to create the image. 
  223.  
  224. 1.8   Color Map
  225.  
  226. The color palette to be used when displaying an image with 16 or fewer 
  227. colors.  See Section 3, "Color Palettes", for further information. 
  228.  
  229. 1.9   Reserved
  230.  
  231. This member was used to indicate the appropriate MS-DOS video mode in 
  232. previous PCX file format versions.  It is ignored in Version 5, but
  233. should be set to zero.
  234.  
  235. 1.10  NPlanes
  236.  
  237. The number of color planes used to display the image (typically 1 or 4).  
  238. See Section 3, "Color Palettes", for further information. 
  239.  
  240. 1.11  Bytes per Line
  241.  
  242. The number of bytes required for a buffer when decoding one color plane 
  243. scan line.  This value should be an even number (for compatibility with 
  244. some existing commercial programs).  See Section 2, "Image Encoding and 
  245. Decoding", for further information. 
  246.  
  247. 1.12  Palette Info (3)
  248.  
  249. A bit-mapped variable indicating how to interpret the color palette.  
  250. Only the lowest two bits are  significant; the others are ignored.  It 
  251. can have one of two possible values: 
  252.  
  253.     0x01 - color or black & white
  254.     0x02 - grayscale
  255.  
  256. If the variable is set to 0x02 (grayscale), the color palette must be set 
  257. to shades of gray. 
  258.  
  259. 1.13  HScreen Size (4)
  260.  
  261. Horizontal screen size in pixels.
  262.  
  263. 1.14  VScreen Size (4)
  264.  
  265. Vertical screen size in pixels.
  266.  
  267. 1.15  Filler
  268.  
  269. Blank space to fill out 128-byte header.  All bytes within this member  
  270. should be set to zero. 
  271.  
  272.  
  273.                                                                     p. 4
  274.  
  275. Notes
  276.  
  277. 1. ZSoft has reserved the right to change the encoding scheme for better 
  278.    image compression performance in future versions. 
  279.  
  280. 2. Horizontal and vertical resolution for video display adapters is 
  281.    defined as the total number of displayed pixels for the current video 
  282.    mode.  For scanners, it is defined in terms of dots per inch.  (These 
  283.    values are provided for information only.  They are not required for 
  284.    encoding or decoding PCX image files.) 
  285.  
  286. 3. The "palette info" member of the file header was used in previous 
  287.    versions of the PCX file format to indicate whether the palette 
  288.    represented a color or grayscale palette.  If it was set to 0x02 (as a 
  289.    bitmap - the upper 6 bits could be set at random), the file decoding 
  290.    functions could assume a default grayscale palette if necessary.  
  291.    However, the palette already had a true (and possibly nonlinear) 
  292.    grayscale, so the "palette info" member was never really used by 
  293.    ZSoft.  The current PC Paintbrush IV and IV Plus products simply 
  294.    ignore it. 
  295.  
  296. 4. The "HScreen Size" and "VScreen Size" members were added to Version 5 
  297.    of the PCX format to support PC Paintbrush IV Version 1.02 and IV Plus 
  298.    Version 1.0.  Since earlier Version 5 PCX files may contain 
  299.    uninitialized data in place of these members, ZSoft specifically 
  300.    recommends that they not be used to determine the appropriate video 
  301.    mode for displaying the files.
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                                                     p. 5
  335.  
  336. 2.  Image Encoding and Decoding 
  337.  
  338. The PCX graphics file format considers an image to be a contiguous 
  339. sequence (block) of eight-bit bytes representing a bit-mapped raster 
  340. display.  A simple byte-oriented, run-length encoding (RLE) scheme is
  341. used to compress the display data.  When the display is represented by
  342. more than one color plane (such as color images on EGA displays), each
  343. scan line is stored sequentially by color plane. 
  344.  
  345. The run-length encoding scheme uses a byte pair consisting of a "count" 
  346. byte and a following "data" byte to represent sequences of display bytes 
  347. with the same value.  A count byte is uniquely identified by having its 
  348. two most significant bits set; its six least significant bits are used to 
  349. represent the count value (1 to 63).  The following data byte is the 
  350. value that is repeated in the display data the number of times indicated 
  351. by the count value. 
  352.  
  353. Any display data byte which is not part of a sequence of bytes of the 
  354. same value and which does not have its two most significant bits set is 
  355. stored as itself in the encoded image data.  Single display data bytes 
  356. with a value of 0xc0 or greater are encoded with a count value of one. 
  357.  
  358. 2.1.  Decoding
  359.  
  360. Decoding display data from encoded image data is done on a line-by-line 
  361. basis.  The pixel dimensions of the displayed image are calculated as: 
  362.  
  363.     horz_size = Window.xlr - Window.xul + 1
  364.  
  365. and
  366.  
  367.     vert_size = Window.ylr - Window.yul + 1
  368.  
  369. The number of bytes required to buffer one complete scan line for all 
  370. color planes in sequence is: 
  371.  
  372.     buffer_size = NPlanes * Bytes per Line
  373.  
  374. Since there are always an integral number of bytes in the buffer, there 
  375. may be unused data at the end of each color plane scan line if the number 
  376. of bits per pixel is other than eight.  This unused data should be masked 
  377. off when transferring the line buffer contents to the video display 
  378. adapter memory. 
  379.  
  380. In theory, each color plane scan line may contain an even or odd number 
  381. of bytes.  However, some application programs expect an even number of 
  382. bytes.  ZSoft ensures that their products create PCX files with an even 
  383. number of bytes per color plane scan line, and recommends that other 
  384. programs do the same for compatibility.  Of course, decoding functions 
  385. should be able to read files with either an even or odd number of bytes 
  386. per color plane scan line. 
  387.  
  388. Decoding begins with the first scan line and proceeds by examining each 
  389. byte of the encoded image data.  If the two most significant bits of the 
  390. byte are set, the lower six bits indicate how many times the next byte is 
  391.  
  392.  
  393.  
  394.  
  395.                                                                     p. 6
  396.  
  397. Decoding begins with the first scan line and proceeds by examining each 
  398. byte of the encoded image data.  If the two most significant bits of the 
  399. byte are set, the lower six bits indicate how many times the next byte is 
  400. to be duplicated in the line buffer.  If these two bits are not set, the 
  401. byte itself is copied (once) to the line buffer.  A count is kept of the 
  402. number of bytes in the line buffer.  The current scan line is complete 
  403. when its value equals "buffer_size". 
  404.  
  405. If the display contains more than one color plane, each plane is decoded 
  406. in sequence.  The order in which they are decoded is device-dependent.  
  407. For instance, the Enhanced Graphics Adapter has four color planes ordered 
  408. as blue, green, red and intensity.  The beginning of each color plane 
  409. scan line within the line buffer is given by: 
  410.  
  411.     offset = plane_number * Bytes per Line
  412.  
  413. where "plane_number" is a number between 0 and NPlanes - 1. 
  414.  
  415. A decoding break occurs at the end of each scan line.  That is, an 
  416. encoding byte pair can only represent a contiguous sequence of bytes 
  417. within the current scan line.  However, this is not necessarily true for 
  418. color planes.  An encoding byte pair may represent a contiguous sequence 
  419. of identical bytes that extends across two color planes for one display 
  420. image scan line. 
  421.  
  422. Decoding continues until all scan lines (as indicated by "vert_size") 
  423. have been decoded.  Some older versions of PC Paintbrush padded the image 
  424. with extra (uninitialized) scan lines so that all blocks of scan lines (8 
  425. or 16 lines) read from the file were the same size.  The image data was 
  426. read until end-of-file was returned.  ZSoft no longer uses this 
  427. technique, since it conflicts with the appended color palette (see 
  428. Subsection 3.3, "VGA 256-Color Palettes").  The extra data read could 
  429. also overrun the user's image buffer. 
  430.  
  431. A sample C function to decode a complete image scan line (all color planes)
  432. from a PCX file is shown in Figure 3. 
  433.  
  434. 2.2.  Encoding
  435.  
  436. Encoding display image data is also done on a line-by-line basis, 
  437. following the order of scan lines stored in the display adapter's memory 
  438. buffer.  The current scan line is encoded for each color plane on a per-
  439. byte basis.  As noted above, ZSoft recommends that all color plane scan 
  440. lines be padded if necessary to ensure they contain an even number of 
  441. bytes. 
  442.  
  443. ZSoft also recommends that the data used to pad the last one or two bytes 
  444. of a scan line represent white data.  Apparently, some application 
  445. programs display this data when printing or faxing the files.
  446.  
  447. A sample C function to encode a single monochrome or color image scan 
  448. line for a PCX file is shown in Figure 4.
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.                                                                     p. 7
  457.  
  458. 3.  Color Palettes 
  459.  
  460. The PCX file format supports color palettes of up to 16 colors in the 
  461. file header.  Larger palettes (up to a maximum of 256 colors) are stored 
  462. in an optional color palette that is appended to the encoded image data 
  463. portion of the file. 
  464.  
  465. The file header color palette has two different formats, both designed 
  466. for IBM PC-compatible machines.  A device-specific palette is used for 
  467. Color Graphics Adapters (CGA),  and a standard R-G-B palette is used for 
  468. Enhanced Graphics Adapters (EGA), Multicolor Graphics Adapters (MCGA), 
  469. Video Graphics Adapters (VGA) and extended Video Graphics Adapters 
  470. (SuperVGA). 
  471.  
  472. ZSoft's PC Paintbrush products no longer support the CGA color palette.  
  473. The following information is provided only for compatibility with older 
  474. PCX files. 
  475.  
  476. 3.1.  CGA Color Palettes
  477.  
  478. The PCX format supports eight possible CGA color palettes for video modes 
  479. 4 (320x200 4-color graphics) and 5 (320x200 monochrome graphics, color 
  480. burst off).  Each palette consists of a background color and three 
  481. foreground colors (or shades of grey).  The background can be one of 16 
  482. colors, the value for which is stored in the first byte of the PCX file 
  483. header Color Map member.  Only the upper four bits are significant; the 
  484. value must be right-shifted by four bits (or divided by 16) to determine 
  485. the appropriate CGA hardware palette register value. 
  486.  
  487. The foreground color palette is specified by the fourth byte of the Color 
  488. Map, which has the following structure: 
  489.  
  490.     Name                Bit    Description
  491.  
  492.     Color Burst Enable   7     0 - color
  493.                                1 - monochrome
  494.     Palette              6     0 - yellow
  495.                                1 - white
  496.     Intensity            5     0 - dim
  497.                                1 - bright
  498.  
  499. The lower five bits are ignored. 
  500.  
  501. Most published descriptions of the ROM BIOS call "Set CGA Palette" 
  502. (Interrupt 16, Function 11) document only two palettes, obtainable by 
  503. setting register BL to 0x00 or 0x01.  This is equivalent to the "Palette" 
  504. bit above.  However, the palette intensity (equivalent to the "Intensity" 
  505. bit above) can be selected using bit 4 of the BL register (0 = dim, 1 = 
  506. bright). 
  507.  
  508. The original CGA display adapter was designed for use with NTSC composite 
  509. video monitors and color televisions.  The "color burst" is a periodic 
  510. burst of a 3.58 MHz signal superimposed on the composite video signal to 
  511. synchronize the phase of the monitor's internal 3.58 MHz oscillator.  
  512. (Without synchronization, the picture has drifting color bars.)  The 
  513. presence or absence of the burst determines whether the image is 
  514. displayed in color or monochrome. 
  515.  
  516.  
  517.                                                                     p. 8
  518.  
  519. The "Color Burst Enable" bit above actually indicates whether the MS-DOS 
  520. video mode is to be 4 (color) or 5 (monochrome).  However, the color 
  521. burst signal has no meaning for RGB monitors.  Video mode 5 will produce 
  522. only two distinct color palettes on CGA displays adapters with RGB 
  523. monitors, and three distinct palettes on EGA, VGA and SuperVGA display 
  524. adapters emulating a CGA display. 
  525.  
  526. Under video mode 6 (640 x 200 2-color graphics), the first byte of the
  527. CGA color palette specifies the foreground color (i.e. - the color of
  528. the displayed pixels).
  529.  
  530. 3.2.  EGA/VGA 16-Color Palettes
  531.  
  532. The 16-color palette for EGA, MCGA, VGA and SuperVGA displays is an array 
  533. of 16 elements, each a structure with the following members: 
  534.  
  535.     Name    Bytes    Description
  536.  
  537.     Red       1      Red intensity
  538.     Green     1      Green intensity
  539.     Blue      1      Blue intensity
  540.  
  541. All color map entries are stored as unsigned bytes with values ranging 
  542. between 0 and 255.  Where display adapters support fewer intensity 
  543. levels, the value of each color map entry is interpreted by dividing its 
  544. value by 256/n, where n is the number of allowable intensity levels 
  545. (typically 2, 4 or 16). 
  546.  
  547. 3.3.  VGA 256-Color Palettes
  548.  
  549. The 256-color palette for MCGA, VGA and SuperVGA displays is an array of 
  550. 256 elements, each a structure with the same members as the EGA/VGA 16-
  551. color palette, which is appended to the encoded image data portion of the 
  552. file (see Figure 1).  It is always preceded by a constant byte flag with
  553. the value 0x0c (12 decimal). 
  554.  
  555. Only Version 5 PCX-format files support 256-color palettes, and then only 
  556. when the image has more than 16 colors.  ZSoft recommends the following 
  557. technique to determine if a 256-color palette is present: first verify 
  558. that the file version number is 5, then count back 769 bytes from the end 
  559. of the file.  If the value of this byte is not 0x0c, the optional 256-
  560. color palette is not present and the EGA/VGA 16-color file header palette 
  561. should be used. 
  562.  
  563. It is possible that a Version 5 PCX-format file with a valid file header 
  564. palette can have the value 0x0c in the 769th byte from the end of the 
  565. encoded image data.  The above technique would then falsely indicate the
  566. presence of an appended 256-color palette.  To avoid this problem, it is 
  567. necessary to first decode the image and note the file position where the 
  568. encoded image data section ends before counting back 769 bytes from the 
  569. end of the file.  If the supposed 256-color palette flag is located in 
  570. the image data section, then the file header palette should be used 
  571. instead.
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.                                                                     p. 9
  579.  
  580. 3.4.  24-Bit Color 
  581.  
  582. Future versions of ZSoft's Publisher's Paintbrush will support up to 16.7 
  583. million simultaneous colors.  The PCX file format will be based on three 
  584. color planes (red, green and blue), with 8 bits per pixel per plane.  
  585. There will be no color palette, since the color of each pixel will be 
  586. fully specified by the encoded image data. 
  587.  
  588. 3.5.  Disabling the Palette 
  589.  
  590. It is occasionally necessary to disable the color palette of a PCX file 
  591. in order to correctly display the image.  In other words, the current 
  592. (default) setting of the display adapter's palette registers are used.  
  593. This can be done by changing the PCX file version number from '5' to '3' 
  594. (i.e. - PC Paintbrush Version 2.8 without palette information).  The file 
  595. decoding functions must then check the file version number and ignore the 
  596. color palette if it is set to '3'.
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.                                                                     p. 10
  636.  
  637. 4.  Other Environments 
  638.  
  639. While the PCX file format was designed for MS-DOS machines, it is 
  640. nevertheless possible to display PCX images on other machines.  It will 
  641. generally be necessary to map the image representation (i.e. - window 
  642. dimensions, number of color planes, bits per pixel per plane, and the 
  643. color palette) to the capabilities of the display hardware. 
  644.  
  645. It is also necessary to remember that all information in a PCX-format 
  646. file is stored as either 8-bit bytes or 16-bit words.  Words are stored 
  647. in the big-endian format characteristic of 80x86-based machines.  That 
  648. is, the eight least significant bits (lower byte) are stored first, 
  649. followed by the eight most significant bits (upper byte).  If PCX-format 
  650. files are transferred to little-endian machines (such as those based on 
  651. 680x0 and Z8000 processors), the order of bytes within each word will 
  652. have to be reversed before they can be interpreted.  (This applies to the 
  653. file header only, since the encoded image data and optional 256-color 
  654. palette are stored as bytes.)
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.                                                                     p. 11
  697.  
  698. References 
  699.  
  700. Azer, S. [1988].  "Working With PCX Files", Microcornucopia, No. 42 
  701. (July-August), p. 42.
  702.  
  703. Lindley, C.A. [1990].  Practical Image Processing in C, John Wiley & Sons 
  704. Inc., New York, N.Y.
  705.  
  706. Luze, M. [1991].  "Printing PCX Files", C Gazette, Vol. 5:2 (Winter 1990 -
  707. 1991), pp. 11-22.
  708.  
  709. Phoenix Technologies Ltd. [1989].  System BIOS for IBM PC/XT/AT Computers 
  710. and Compatibles, Addison-Wesley, Reading, MA.
  711.  
  712. Quirk, K. [1989].  "Translating PCX Files", Dr. Dobb's Journal, Vol. 14:8 
  713. (August), pp. 30-36, 105-108.
  714.  
  715. Rimmer, S. [1990].  Bit-Mapped Graphics, Windcrest Books, Blue Ridge 
  716. Summit, PA.
  717.  
  718. ZSoft Corporation [1988].  PCX Technical Reference Manual Revision 4,
  719. ZSoft Corporation, Marietta, GA.
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.                                                                     p. 12
  758.  
  759. Figures
  760.  
  761. +--------------------------------------------+
  762. |    File Header (128 bytes)                 |
  763. +--------------------------------------------+
  764. |    Encoded Image Data (variable length)    |
  765. +--------------------------------------------+
  766. |    Optional Color Palette (769 bytes)      |
  767. +--------------------------------------------+
  768.  
  769. Figure 1 - Basic PCX File Format
  770.  
  771.  
  772. Name           Bytes  Description 
  773.  
  774. PCX Flag         1    Constant flag
  775. Version          1    PCX version number
  776. Encoding         1    Run-length encoding flag
  777. Bits per Pixel   1    Number of bits per pixel per plane
  778. Window           8    Window dimensions
  779. HDPI             2    Horizontal image resolution
  780. VDPI             2    Vertical image resolution
  781. Color Map       48    Hardware R-G-B color palette
  782. Reserved         1    (Used to contain video mode)
  783. NPlanes          1    Number of color planes
  784. Bytes per Line   2    Number of bytes per scan line
  785. Palette Info     2    Palette interpretation
  786. HScreen Size     2    Horizontal screen size
  787. VScreen Size     2    Vertical screen size
  788. Filler          54    Initialized filler bytes
  789.  
  790. Figure 2 - PCX File Header Structure
  791.  
  792.  
  793. /* Read an encoded scan line (all color planes) from a          */
  794. /* PCX-format image file and write the decoded data to a scan   */
  795. /* line buffer                                                  */
  796.  
  797. void pcx_read_line
  798. (
  799.   unsigned char *linep, /* PCX scan line buffer pointer         */
  800.   FILE *fp,             /* PCX image file pointer               */
  801.   int bpline            /* # bytes per line (all color planes)  */
  802. )
  803. {
  804.   int data;         /* Image data byte                          */
  805.   int count;        /* Image data byte repeat count             */
  806.   int offset = 0;   /* Scan line buffer offset                  */
  807.  
  808.   while (offset < bpline)   /* Decode current scan line         */
  809.   {
  810.     data = getc(fp);        /* Get next byte                    */
  811.  
  812.     /* If top two bits of byte are set, lower six bits show how */
  813.     /* many times to duplicate next byte                        */
  814.  
  815.  
  816.  
  817.  
  818.                                                                     p. 13
  819.  
  820.     if ((data & 0xc0) == 0xc0)
  821.     {
  822.       count = data & 0x3f;          /* Mask off repeat count    */
  823.       data = getc(fp);              /* Get next byte            */
  824.       memset(linep, data, count);   /* Duplicate byte           */
  825.       linep += count;
  826.       offset += count;
  827.     }
  828.     else
  829.     {
  830.       *linep++ = (unsigned char) data;  /* Copy byte            */
  831.       offset++;
  832.     }
  833.   }
  834. }
  835.  
  836. Figure 3 - Decode PCX Image File Scan Line Function
  837.  
  838.  
  839. /* Encode a scan line and write it to a PCX file (the line is   */
  840. /* assumed to contain the color plane scan lines in sequence,   */
  841. /* with padding for an even number of bytes and trailing white  */
  842. /* data for each line as appropriate)                           */
  843.  
  844. void pcx_write_line
  845. (
  846.   unsigned char *linep, /* Scan line buffer pointer             */
  847.   int length,           /* Scan line buffer length (in bytes)   */
  848.   FILE *fp              /* PCX file pointer                     */
  849. )
  850. {
  851.   int curr_data;        /* Current data byte                    */
  852.   int prev_data;        /* Previous data byte                   */
  853.   int data_count;       /* Data repeat count                    */
  854.   int line_count;       /* Scan line byte count                 */
  855.  
  856.   prev_data = *linep++; /* Initialize the previous data byte    */
  857.   data_count = 1;
  858.   line_count = 1;
  859.  
  860.   while (line_count < length)   /* Encode scan line             */
  861.   {
  862.     curr_data = *linep++;       /* Get the current data byte    */
  863.     line_count++;               /* Increment line byte count    */
  864.  
  865.     if (curr_data == prev_data) /* Repeating data bytes ?       */
  866.     {
  867.       data_count++;             /* Increment data repeat count  */
  868.  
  869.       if (data_count == 0x3f)   /* Max allowable repeat count ? */
  870.       {
  871.         pcx_encode(prev_data, data_count, fp);  /* Encode data  */
  872.         data_count = 0;
  873.       }
  874.     }
  875.  
  876.  
  877.  
  878.  
  879.                                                                     p. 14
  880.  
  881.     else    /* End of repeating data bytes                      */
  882.     {
  883.       if (data_count > 0)
  884.         pcx_encode(prev_data, data_count, fp);  /* Encode data  */
  885.  
  886.       prev_data = curr_data;    /* Current data byte now prev   */
  887.       data_count = 1;
  888.     }
  889.   }
  890.  
  891.   if (data_count > 0)           /* Any remaining data ?         */
  892.   {
  893.     pcx_encode(prev_data, data_count, fp);      /* Encode data  */
  894.   }
  895. }
  896.  
  897.  
  898. /* Write an encoded byte pair (or single byte) to a file        */
  899.  
  900. void pcx_encode
  901. (
  902.   int data,     /* Data byte                                    */
  903.   int count,    /* Data byte repeat count                       */
  904.   FILE *fp      /* PCX file pointer                             */
  905. )
  906. {
  907.   if (((data & 0xc0) == 0xc0) || count > 1)
  908.   {
  909.     putc(0xc0 | count, fp);     /* Write count byte             */
  910.   }
  911.  
  912.   putc(data, fp);       /* Write data byte                      */
  913. }
  914.  
  915. Figure 4 - Encode Image Scan Line Functions
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.                                                                     p. 15
  941.  
  942.